--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
docs/source/interfaces.rst 55c95bf59a06127d60de76a12474fd21fc086a2d (55c95bf5) Text, 53.89 KB
Tb4b4b4.. Tff7b72_interfaces-main:
Tc9d1d9**********************
Tc9d1d9Configuring Interfaces
Tc9d1d9**********************
Reticulum supports using many kinds of devices as networking interfaces, and
allows you to mix and match them in any way you choose. The number of distinct
network topologies you can create with Reticulum is more or less endless, but
common to them all is that you will need to define one or more *interfaces*
for Reticulum to use.
The following sections describe the interfaces currently available in Reticulum,
and gives example configurations for the respective interface types.
For a high-level overview of how networks can be formed over different interface
types, have a look at the Te6edf3:ref:Te6edf3`Building Networks<networks-main>` chapter of this
manual.
Tb4b4b4.. Tff7b72_interfaces-custom:
Tc9d1d9Custom Interfaces
Tc9d1d9=================
In addition to the built-in interface types, Reticulum is **fully extensible** with
custom, user- or community-supplied interfaces, and creating custom interface
modules is straightforward. Please see the Te6edf3:ref:Te6edf3`custom interface<example-custominterface>`
example for basic interface code to build upon.
Tb4b4b4.. Tff7b72_interfaces-auto:
Tc9d1d9Auto Interface
Tc9d1d9==============
The Ta5d6ff``Ta5d6ffAutoInterfaceTa5d6ff`` enables communication with other discoverable Reticulum
nodes over any kind of local Ethernet or WiFi-based medium. Even though it uses IPv6 for peer
discovery, and UDP for packet transport, it **does not** need any functional IP
infrastructure like routers or DHCP servers, on your physical network.
Tb4b4b4.. Tff7b72warningTb4b4b4::
If you have **firewall** software running on your computer, it may block traffic
required for Ta5d6ff``Ta5d6ffAutoInterfaceTa5d6ff`` to work. If this is the case, you will have to
allow UDP traffic on port Ta5d6ff``Ta5d6ff29716Ta5d6ff`` and Ta5d6ff``Ta5d6ff42671Ta5d6ff``.
As long as there is at least some sort of switching medium present between peers (a
wired switch, a hub, a WiFi access point or similar, or simply two devices connected
directly by Ethernet cable), it will work without any configuration, setup or intermediary devices.
For Ta5d6ff``Ta5d6ffAutoInterfaceTa5d6ff`` peer discovery to work, it's also required that link-local
IPv6 support is available on your system, which it should be by default in all
current operating systems, both desktop and mobile.
Tb4b4b4.. Tff7b72noteTb4b4b4::
Almost all current Ethernet and WiFi hardware will work without any kind
of configuration or setup with Ta5d6ff``Ta5d6ffAutoInterfaceTa5d6ff``, but a small subset of
devices turn on options that limit device-to-device communication by default,
resulting in Ta5d6ff``Ta5d6ffAutoInterfaceTa5d6ff`` peer discovery being blocked. This issue is
most commonly seen on very cheap, ISP-supplied WiFi routers, and can sometimes
be turned off in the router configuration.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# This example demonstrates a bare-minimum setup
T8b949e# of an Auto Interface. It will allow communica-
T8b949e# tion with all other reachable devices on all
T8b949e# usable physical ethernet-based devices that
T8b949e# are available on the system.
Tff7b72[[Default Interface]]
Te6edf3type Tff7b72= Ta5d6ffAutoInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# This example demonstrates an more specifically
T8b949e# configured Auto Interface, that only uses spe-
T8b949e# cific physical interfaces, and has a number of
T8b949e# other configuration options set.
Tff7b72[[Default Interface]]
Te6edf3type Tff7b72= Ta5d6ffAutoInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# You can create multiple isolated Reticulum
T8b949e# networks on the same physical LAN by
T8b949e# specifying different Group IDs.
Te6edf3group_id Tff7b72= Ta5d6ffreticulum
T8b949e# You can also choose the multicast address type:
T8b949e# temporary (default, Temporary Multicast Address)
T8b949e# or permanent (Permanent Multicast Address)
Te6edf3multicast_address_type Tff7b72= Ta5d6ffpermanent
T8b949e# You can also select specifically which
T8b949e# kernel networking devices to use.
Te6edf3devices Tff7b72= Ta5d6ffwlan0,eth1
T8b949e# Or let AutoInterface use all suitable
T8b949e# devices except for a list of ignored ones.
Te6edf3ignored_devices Tff7b72= Ta5d6fftun0,eth0
If you are connected to the Internet with IPv6, and your provider will route
IPv6 multicast, you can potentially configure the Auto Interface to globally
autodiscover other Reticulum nodes within your selected Group ID. You can specify
the discovery scope by setting it to one of Ta5d6ff``Ta5d6fflinkTa5d6ff``, Ta5d6ff``Ta5d6ffadminTa5d6ff``, Ta5d6ff``Ta5d6ffsiteTa5d6ff``,
Ta5d6ff``Ta5d6fforganisationTa5d6ff`` or Ta5d6ff``Ta5d6ffglobalTa5d6ff``.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[Default Interface]]
Te6edf3type Tff7b72= Ta5d6ffAutoInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# Configure global discovery
Te6edf3group_id Tff7b72= Ta5d6ffcustom_network_name
Te6edf3discovery_scope Tff7b72= Ta5d6ffglobal
T8b949e# Other configuration options
Te6edf3discovery_port Tff7b72= Ta5d6ff48555
Te6edf3data_port Tff7b72= Ta5d6ff49555
Tb4b4b4.. Tff7b72_interfaces-backbone:
Tc9d1d9Backbone Interface
Tc9d1d9====================
The Backbone interface is a very fast and resource efficient interface type, primarily
intended for interconnecting Reticulum instances over many different types of mediums.
It uses a kernel-event I/O backend, and can handle thousands of interfaces and/or clients
with relatively low system resource utilisation. **This interface type is currently only
supported on Linux and Android**.
Tb4b4b4.. Tff7b72noteTb4b4b4::
The Backbone Interface is fully compatible with the Ta5d6ff``Ta5d6ffTCPServerInterfaceTa5d6ff`` and Ta5d6ff``Ta5d6ffTCPClientInterfaceTa5d6ff``
types, and they can be used interchangably, and cross-connect with each other. On systems that support
Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff``, it is generally recommended to use it, unless you need specific options or
features that the TCP server and client interfaces provide.
While the goal is to support *all* socket types and I/O devices provided by the underlying
operating system, the initial release only provides support for TCP connections over IPv4
and IPv6.
For all types of connections over a Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff``, Reticulum will gracefully
handle intermittency, link loss, and connections that come and go.
Tc9d1d9Listeners
Tc9d1d9---------
The following examples illustrates various ways to set up Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff`` listeners.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# This example demonstrates a backbone interface
T8b949e# that listens for incoming connections on the
T8b949e# specified IP address and port number.
Tff7b72[[Backbone Listener]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3listen_on Tff7b72= Ta5d6ff0.0.0.0
Te6edf3port Tff7b72= Ta5d6ff4242
T8b949e# Alternatively you can bind to a specific IP
Tff7b72[[Backbone Listener]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3listen_on Tff7b72= Ta5d6ff10.0.0.88
Te6edf3port Tff7b72= Ta5d6ff4242
T8b949e# Or a specific network device
Tff7b72[[Backbone Listener]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3device Tff7b72= Ta5d6ffeth0
Te6edf3port Tff7b72= Ta5d6ff4242
If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
you can use the Ta5d6ff``Ta5d6ffprefer_ipv6Ta5d6ff`` option to bind to the IPv6 address:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# This example demonstrates a backbone interface
T8b949e# listening on the IPv6 address of a specified
T8b949e# kernel networking device.
Tff7b72[[Backbone Listener]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3prefer_ipv6 Tff7b72= Ta5d6ffyes
Te6edf3device Tff7b72= Ta5d6ffeth0
Te6edf3port Tff7b72= Ta5d6ff4242
To use the Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff`` over Ta5d6ff`Yggdrasil Tffd700<https://yggdrasil-network.github.io/>Ta5d6ff`_, you
can simply specify the Yggdrasil Ta5d6ff``Ta5d6fftunTa5d6ff`` device and a listening port, like so:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# This example demonstrates a backbone interface
T8b949e# listening for connections over Yggdrasil.
Tff7b72[[Yggdrasil Backbone Interface]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3device Tff7b72= Ta5d6fftun0
Te6edf3port Tff7b72= Ta5d6ff4343
Tc9d1d9Connecting Remotes
Tc9d1d9------------------
The following examples illustrates various ways to connect to remote Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff`` listeners.
As noted above, Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff`` interfaces can also connect to remote Ta5d6ff``Ta5d6ffTCPServerInterfaceTa5d6ff``,
and as such these interface types can be used interchangably.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# Here's an example of a backbone interface that
T8b949e# connects to a remote listener.
Tff7b72[[Backbone Remote]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3remote Tff7b72= Ta5d6ffamsterdam.connect.reticulum.network
Te6edf3target_port Tff7b72= Ta5d6ff4251
To connect to remotes over Ta5d6ff`Yggdrasil Tffd700<https://yggdrasil-network.github.io/>Ta5d6ff`_, simply
specify the target Yggdrasil IPv6 address and port, like so:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[Yggdrasil Remote]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3target_host Tff7b72= Ta5d6ff201:5d78:af73:5caf:a4de:a79f:3278:71e5
Te6edf3target_port Tff7b72= Ta5d6ff4343
Tb4b4b4.. Tff7b72_interfaces-tcps:
Tc9d1d9TCP Server Interface
Tc9d1d9====================
The TCP Server interface is suitable for allowing other peers to connect over
the Internet or private IPv4 and IPv6 networks. When a TCP server interface has been
configured, other Reticulum peers can connect to it with a TCP Client interface.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# This example demonstrates a TCP server interface.
T8b949e# It will listen for incoming connections on all IP
T8b949e# interfaces on port 4242.
Tff7b72[[TCP Server Interface]]
Te6edf3type Tff7b72= Ta5d6ffTCPServerInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3listen_ip Tff7b72= Ta5d6ff0.0.0.0
Te6edf3listen_port Tff7b72= Ta5d6ff4242
T8b949e# Alternatively you can bind to a specific IP
Tff7b72[[TCP Server Interface]]
Te6edf3type Tff7b72= Ta5d6ffTCPServerInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3listen_ip Tff7b72= Ta5d6ff10.0.0.88
Te6edf3listen_port Tff7b72= Ta5d6ff4242
T8b949e# Or a specific network device
Tff7b72[[TCP Server Interface]]
Te6edf3type Tff7b72= Ta5d6ffTCPServerInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3device Tff7b72= Ta5d6ffeth0
Te6edf3listen_port Tff7b72= Ta5d6ff4242
If you are using the interface on a device which has both IPv4 and IPv6 addresses available,
you can use the Ta5d6ff``Ta5d6ffprefer_ipv6Ta5d6ff`` option to bind to the IPv6 address:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# This example demonstrates a TCP server interface.
T8b949e# It will listen for incoming connections on the
T8b949e# specified IP address and port number.
Tff7b72[[TCP Server Interface]]
Te6edf3type Tff7b72= Ta5d6ffTCPServerInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3prefer_ipv6 Tff7b72= Ta5d6ffTrue
Te6edf3device Tff7b72= Ta5d6ffeth0
Te6edf3port Tff7b72= Ta5d6ff4242
To use the TCP Server Interface over Ta5d6ff`Yggdrasil Tffd700<https://yggdrasil-network.github.io/>Ta5d6ff`_, you
can simply specify the Yggdrasil Ta5d6ff``Ta5d6fftunTa5d6ff`` device and a listening port, like so:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[Yggdrasil TCP Server Interface]]
Te6edf3type Tff7b72= Ta5d6ffTCPServerInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3device Tff7b72= Ta5d6fftun0
Te6edf3listen_port Tff7b72= Ta5d6ff4343
Tb4b4b4.. Tff7b72noteTb4b4b4::
The TCP interfaces support tunneling over I2P, but to do so reliably,
you must use the i2p_tunneled option:
Tb4b4b4.. Tff7b72codeTb4b4b4::
[[TCP Server on I2P]]
type = TCPServerInterface
enabled = yes
listen_ip = 127.0.0.1
listen_port = 5001
i2p_tunneled = yes
In almost all cases, it is easier to use the dedicated Ta5d6ff``Ta5d6ffI2PInterfaceTa5d6ff``, but for complete
control, and using I2P routers running on external systems, this option also exists.
Tb4b4b4.. Tff7b72_interfaces-tcpc:
Tc9d1d9TCP Client Interface
Tc9d1d9====================
To connect to a TCP server interface, you can use the TCP client
interface. Many TCP Client interfaces from different peers can connect to the
same TCP Server interface at the same time.
The TCP interface types can also tolerate intermittency in the IP link layer.
This means that Reticulum will gracefully handle IP links that go up and down,
and restore connectivity after a failure, once the other end of a TCP interface reappears.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# Here's an example of a TCP Client interface. The
T8b949e# target_host can be a hostname or an IPv4 or IPv6 address.
Tff7b72[[TCP Client Interface]]
Te6edf3type Tff7b72= Ta5d6ffTCPClientInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3target_host Tff7b72= Ta5d6ff127.0.0.1
Te6edf3target_port Tff7b72= Ta5d6ff4242
To use the TCP Client Interface over Ta5d6ff`Yggdrasil Tffd700<https://yggdrasil-network.github.io/>Ta5d6ff`_, simply
specify the target Yggdrasil IPv6 address and port, like so:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[Yggdrasil TCP Client Interface]]
Te6edf3type Tff7b72= Ta5d6ffTCPClientInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3target_host Tff7b72= Ta5d6ff201:5d78:af73:5caf:a4de:a79f:3278:71e5
Te6edf3target_port Tff7b72= Ta5d6ff4343
It is also possible to use this interface type to connect via other programs
or hardware devices that expose a KISS interface on a TCP port, for example
software-based soundmodems. To do this, use the Ta5d6ff``Ta5d6ffkiss_framingTa5d6ff`` option:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# Here's an example of a TCP Client interface that connects
T8b949e# to a software TNC soundmodem on a KISS over TCP port.
Tff7b72[[TCP KISS Interface]]
Te6edf3type Tff7b72= Ta5d6ffTCPClientInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3kiss_framing Tff7b72= Ta5d6ffTrue
Te6edf3target_host Tff7b72= Ta5d6ff127.0.0.1
Te6edf3target_port Tff7b72= Ta5d6ff8001
Te6edf3fixed_mtu Tff7b72= Ta5d6ff500
**Caution!** Only use the KISS framing option when connecting to external devices
and programs like soundmodems and similar over TCP. When using the
Ta5d6ff``Ta5d6ffTCPClientInterfaceTa5d6ff`` in conjunction with the Ta5d6ff``Ta5d6ffTCPServerInterfaceTa5d6ff`` you should
never enable Ta5d6ff``Ta5d6ffkiss_framingTa5d6ff``, since this will disable internal reliability and
recovery mechanisms that greatly improves performance over unreliable and
intermittent TCP links.
For KISS devices that need only supports a particular MTU, you can use the
Ta5d6ff``Ta5d6fffixed_mtuTa5d6ff`` option.
Tb4b4b4.. Tff7b72noteTb4b4b4::
The TCP interfaces support tunneling over I2P, but to do so reliably,
you must use the i2p_tunneled option:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[TCP Client over I2P]]
Te6edf3type Tff7b72= Ta5d6ffTCPClientInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3target_host Tff7b72= Ta5d6ff127.0.0.1
Te6edf3target_port Tff7b72= Ta5d6ff5001
Te6edf3i2p_tunneled Tff7b72= Ta5d6ffyes
Tb4b4b4.. Tff7b72_interfaces-udp:
Tc9d1d9UDP Interface
Tc9d1d9=============
A UDP interface can be useful for communicating over IP networks, both
private and the internet. It can also allow broadcast communication
over IP networks, so it can provide an easy way to enable connectivity
with all other peers on a local area network.
Tb4b4b4.. Tff7b72warningTb4b4b4::
Using broadcast UDP traffic has performance implications,
especially on WiFi. If your goal is simply to enable easy communication
with all peers in your local Ethernet broadcast domain, the
Te6edf3:ref:Te6edf3`Auto Interface<interfaces-auto>` performs *much* better, and is even
easier to use.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# This example enables communication with other
T8b949e# local Reticulum peers over UDP.
Tff7b72[[UDP Interface]]
Te6edf3type Tff7b72= Ta5d6ffUDPInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3listen_ip Tff7b72= Ta5d6ff0.0.0.0
Te6edf3listen_port Tff7b72= Ta5d6ff4242
Te6edf3forward_ip Tff7b72= Ta5d6ff255.255.255.255
Te6edf3forward_port Tff7b72= Ta5d6ff4242
T8b949e# The above configuration will allow communication
T8b949e# within the local broadcast domains of all local
T8b949e# IP interfaces.
T8b949e# Instead of specifying listen_ip, listen_port,
T8b949e# forward_ip and forward_port, you can also bind
T8b949e# to a specific network device like below.
T8b949e# device = eth0
T8b949e# port = 4242
T8b949e# Assuming the eth0 device has the address
T8b949e# 10.55.0.72/24, the above configuration would
T8b949e# be equivalent to the following manual setup.
T8b949e# Note that we are both listening and forwarding to
T8b949e# the broadcast address of the network segments.
T8b949e# listen_ip = 10.55.0.255
T8b949e# listen_port = 4242
T8b949e# forward_ip = 10.55.0.255
T8b949e# forward_port = 4242
T8b949e# You can of course also communicate only with
T8b949e# a single IP address
T8b949e# listen_ip = 10.55.0.15
T8b949e# listen_port = 4242
T8b949e# forward_ip = 10.55.0.16
T8b949e# forward_port = 4242
Tb4b4b4.. Tff7b72_interfaces-i2p:
Tc9d1d9I2P Interface
Tc9d1d9=============
The I2P interface lets you connect Reticulum instances over the
Ta5d6ff`Invisible Internet Protocol Tffd700<https://i2pd.website>Ta5d6ff`_. This can be
especially useful in cases where you want to host a globally reachable
Reticulum instance, but do not have access to any public IP addresses,
have a frequently changing IP address, or have firewalls blocking
inbound traffic.
Using the I2P interface, you will get a globally reachable, portable
and persistent I2P address that your Reticulum instance can be reached
at.
To use the I2P interface, you must have an I2P router running
on your system. The easiest way to achieve this is to download and
install the Ta5d6ff`latest release Tffd700<https://github.com/PurpleI2P/i2pd/releases/latest>Ta5d6ff`_
of the Ta5d6ff``Ta5d6ffi2pdTa5d6ff`` package. For more details about I2P, see the
Ta5d6ff`geti2p.net website Tffd700<https://geti2p.net/en/about/intro>Ta5d6ff`_.
When an I2P router is running on your system, you can simply add
an I2P interface to Reticulum:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[I2P]]
Te6edf3type Tff7b72= Ta5d6ffI2PInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3connectable Tff7b72= Ta5d6ffyes
On the first start, Reticulum will generate a new I2P address for the
interface and start listening for inbound traffic on it. This can take
a while the first time, especially if your I2P router was also just
started, and is not yet well-connected to the I2P network. When ready,
you should see I2P base32 address printed to your log file. You can
also inspect the status of the interface using the Ta5d6ff``Ta5d6ffrnstatusTa5d6ff`` utility.
To connect to other Reticulum instances over I2P, just add a comma-separated
list of I2P base32 addresses to the Ta5d6ff``Ta5d6ffpeersTa5d6ff`` option of the interface:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[I2P]]
Te6edf3type Tff7b72= Ta5d6ffI2PInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
Te6edf3connectable Tff7b72= Ta5d6ffyes
Te6edf3peers Tff7b72= Ta5d6ff5urvjicpzi7q3ybztsef4i5ow2aq4soktfj7zedz53s47r54jnqq.b32.i2p
It can take anywhere from a few seconds to a few minutes to establish
I2P connections to the desired peers, so Reticulum handles the process
in the background, and will output relevant events to the log.
Tb4b4b4.. Tff7b72noteTb4b4b4::
While the I2P interface is the simplest way to use
Reticulum over I2P, it is also possible to tunnel the TCP server and
client interfaces over I2P manually. This can be useful in situations
where more control is needed, but requires manual tunnel setup through
the I2P daemon configuration.
It is important to note that the two methods are *interchangably compatible*.
You can use the I2PInterface to connect to a TCPServerInterface that
was manually tunneled over I2P, for example. This offers a high degree
of flexibility in network setup, while retaining ease of use in simpler
use-cases.
Tb4b4b4.. Tff7b72_interfaces-rnode:
Tc9d1d9RNode LoRa Interface
Tc9d1d9====================
To use Reticulum over LoRa, the Ta5d6ff`RNode Tffd700<https://unsigned.io/rnode/>Ta5d6ff`_ interface
can be used, and offers full control over LoRa parameters.
Tb4b4b4.. Tff7b72warningTb4b4b4::
Radio frequency spectrum is a legally controlled resource, and legislation
varies widely around the world. It is your responsibility to be aware of any
relevant regulation for your location, and to make decisions accordingly.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# Here's an example of how to add a LoRa interface
T8b949e# using the RNode LoRa transceiver.
Tff7b72[[RNode LoRa Interface]]
Te6edf3type Tff7b72= Ta5d6ffRNodeInterface
T8b949e# Enable interface if you want use it!
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# Serial port for the device
Te6edf3port Tff7b72= Ta5d6ff/dev/ttyUSB0
T8b949e# You can connect wirelessly to the
T8b949e# RNode device if it supports WiFi.
T8b949e# Connect by IP address
T8b949e# port = tcp://10.0.0.1
T8b949e# Or, connect by hostname
T8b949e# port = tcp://rnodef3b9.local
T8b949e# It is also possible to use BLE devices
T8b949e# instead of wired serial ports. The
T8b949e# target RNode must be paired with the
T8b949e# host device before connecting. BLE
T8b949e# devices can be connected by name,
T8b949e# BLE MAC address or by any available.
T8b949e# Connect to specific device by name
T8b949e# port = ble://RNode 3B87
T8b949e# Or by BLE MAC address
T8b949e# port = ble://F4:12:73:29:4E:89
T8b949e# Or connect to the first available,
T8b949e# paired device
T8b949e# port = ble://
T8b949e# Set frequency to 867.2 MHz
Te6edf3frequency Tff7b72= Ta5d6ff867200000
T8b949e# Set LoRa bandwidth to 125 KHz
Te6edf3bandwidth Tff7b72= Ta5d6ff125000
T8b949e# Set TX power to 7 dBm (5 mW)
Te6edf3txpower Tff7b72= Ta5d6ff7
T8b949e# Select spreading factor 8. Valid
T8b949e# range is 7 through 12, with 7
T8b949e# being the fastest and 12 having
T8b949e# the longest range.
Te6edf3spreadingfactor Tff7b72= Ta5d6ff8
T8b949e# Select coding rate 5. Valid range
T8b949e# is 5 throough 8, with 5 being the
T8b949e# fastest, and 8 the longest range.
Te6edf3codingrate Tff7b72= Ta5d6ff5
T8b949e# You can configure the RNode to send
T8b949e# out identification on the channel with
T8b949e# a set interval by configuring the
T8b949e# following two parameters.
T8b949e# id_callsign = MYCALL-0
T8b949e# id_interval = 600
T8b949e# For certain homebrew RNode interfaces
T8b949e# with low amounts of RAM, using packet
T8b949e# flow control can be useful. By default
T8b949e# it is disabled.
T8b949e# flow_control = False
T8b949e# It is possible to limit the airtime
T8b949e# utilisation of an RNode by using the
T8b949e# following two configuration options.
T8b949e# The short-term limit is applied in a
T8b949e# window of approximately 15 seconds,
T8b949e# and the long-term limit is enforced
T8b949e# over a rolling 60 minute window. Both
T8b949e# options are specified in percent.
T8b949e# airtime_limit_long = 1.5
T8b949e# airtime_limit_short = 33
Tb4b4b4.. Tff7b72_interfaces-rnode-multi:
Tc9d1d9RNode Multi Interface
Tc9d1d9=====================
For RNodes that support multiple LoRa transceivers, the RNode
Multi interface can be used to configure sub-interfaces individually.
Tb4b4b4.. Tff7b72warningTb4b4b4::
Radio frequency spectrum is a legally controlled resource, and legislation
varies widely around the world. It is your responsibility to be aware of any
relevant regulation for your location, and to make decisions accordingly.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
T8b949e# Here's an example of how to add an RNode Multi interface
T8b949e# using the RNode LoRa transceiver.
Tff7b72[[RNode Multi Interface]]
Te6edf3type Tff7b72= Ta5d6ffRNodeMultiInterface
T8b949e# Enable interface if you want to use it!
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# Serial port for the device
Te6edf3port Tff7b72= Ta5d6ff/dev/ttyACM0
T8b949e# You can configure the RNode to send
T8b949e# out identification on the channel with
T8b949e# a set interval by configuring the
T8b949e# following two parameters.
T8b949e# id_callsign = MYCALL-0
T8b949e# id_interval = 600
T8b949e# A subinterface
Tff7b72[[[High Datarate]]]
T8b949e# Subinterfaces can be enabled and disabled in of themselves
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# Set frequency to 2.4GHz
Te6edf3frequency Tff7b72= Ta5d6ff2400000000
T8b949e# Set LoRa bandwidth to 1625 KHz
Te6edf3bandwidth Tff7b72= Ta5d6ff1625000
T8b949e# Set TX power to 0 dBm (0.12 mW)
Te6edf3txpower Tff7b72= Ta5d6ff0
T8b949e# The virtual port, only the manufacturer
T8b949e# or the person who wrote the board config
T8b949e# can tell you what it will be for which
T8b949e# physical hardware interface
Te6edf3vport Tff7b72= Ta5d6ff1
T8b949e# Select spreading factor 5. Valid
T8b949e# range is 5 through 12, with 5
T8b949e# being the fastest and 12 having
T8b949e# the longest range.
Te6edf3spreadingfactor Tff7b72= Ta5d6ff5
T8b949e# Select coding rate 5. Valid range
T8b949e# is 5 throough 8, with 5 being the
T8b949e# fastest, and 8 the longest range.
Te6edf3codingrate Tff7b72= Ta5d6ff5
T8b949e# It is possible to limit the airtime
T8b949e# utilisation of an RNode by using the
T8b949e# following two configuration options.
T8b949e# The short-term limit is applied in a
T8b949e# window of approximately 15 seconds,
T8b949e# and the long-term limit is enforced
T8b949e# over a rolling 60 minute window. Both
T8b949e# options are specified in percent.
T8b949e# airtime_limit_long = 100
T8b949e# airtime_limit_short = 100
Tff7b72[[[Low Datarate]]]
T8b949e# Subinterfaces can be enabled and disabled in of themselves
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# Set frequency to 865.6 MHz
Te6edf3frequency Tff7b72= Ta5d6ff865600000
T8b949e# The virtual port, only the manufacturer
T8b949e# or the person who wrote the board config
T8b949e# can tell you what it will be for which
T8b949e# physical hardware interface
Te6edf3vport Tff7b72= Ta5d6ff0
T8b949e# Set LoRa bandwidth to 125 KHz
Te6edf3bandwidth Tff7b72= Ta5d6ff125000
T8b949e# Set TX power to 0 dBm (0.12 mW)
Te6edf3txpower Tff7b72= Ta5d6ff0
T8b949e# Select spreading factor 7. Valid
T8b949e# range is 5 through 12, with 5
T8b949e# being the fastest and 12 having
T8b949e# the longest range.
Te6edf3spreadingfactor Tff7b72= Ta5d6ff7
T8b949e# Select coding rate 5. Valid range
T8b949e# is 5 throough 8, with 5 being the
T8b949e# fastest, and 8 the longest range.
Te6edf3codingrate Tff7b72= Ta5d6ff5
T8b949e# It is possible to limit the airtime
T8b949e# utilisation of an RNode by using the
T8b949e# following two configuration options.
T8b949e# The short-term limit is applied in a
T8b949e# window of approximately 15 seconds,
T8b949e# and the long-term limit is enforced
T8b949e# over a rolling 60 minute window. Both
T8b949e# options are specified in percent.
T8b949e# airtime_limit_long = 100
T8b949e# airtime_limit_short = 100
Tb4b4b4.. Tff7b72_interfaces-serial:
Tc9d1d9Serial Interface
Tc9d1d9================
Reticulum can be used over serial ports directly, or over any device with a
serial port, that will transparently pass data. Useful for communicating
directly over a wire-pair, or for using devices such as data radios and lasers.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[Serial Interface]]
Te6edf3type Tff7b72= Ta5d6ffSerialInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# Serial port for the device
Te6edf3port Tff7b72= Ta5d6ff/dev/ttyUSB0
T8b949e# Set the serial baud-rate and other
T8b949e# configuration parameters.
Te6edf3speed Tff7b72= Ta5d6ff115200
Te6edf3databits Tff7b72= Ta5d6ff8
Te6edf3parity Tff7b72= Ta5d6ffnone
Te6edf3stopbits Tff7b72= Ta5d6ff1
Tb4b4b4.. Tff7b72_interfaces-pipe:
Tc9d1d9Pipe Interface
Tc9d1d9==============
Using this interface, Reticulum can use any program as an interface via Te6edf3`stdin` and
Te6edf3`stdout`. This can be used to easily create virtual interfaces, or to interface with
custom hardware or other systems.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[Pipe Interface]]
Te6edf3type Tff7b72= Ta5d6ffPipeInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# External command to execute
Te6edf3command Tff7b72= Ta5d6ffnetcat -l 5757
T8b949e# Optional respawn delay, in seconds
Te6edf3respawn_delay Tff7b72= Ta5d6ff5
Reticulum will write all packets to Te6edf3`stdin` of the Ta5d6ff``Ta5d6ffcommandTa5d6ff`` option, and will
continuously read and scan its Te6edf3`stdout` for Reticulum packets. If Ta5d6ff``Ta5d6ffEOFTa5d6ff`` is reached,
Reticulum will try to respawn the program after waiting for Ta5d6ff``Ta5d6ffrespawn_intervalTa5d6ff`` seconds.
Tb4b4b4.. Tff7b72_interfaces-kiss:
Tc9d1d9KISS Interface
Tc9d1d9==============
With the KISS interface, you can use Reticulum over a variety of packet
radio modems and TNCs, including Ta5d6ff`OpenModem Tffd700<https://unsigned.io/openmodem/>Ta5d6ff`_.
KISS interfaces can also be configured to periodically send out beacons
for station identification purposes.
Tb4b4b4.. Tff7b72warningTb4b4b4::
Radio frequency spectrum is a legally controlled resource, and legislation
varies widely around the world. It is your responsibility to be aware of any
relevant regulation for your location, and to make decisions accordingly.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[Packet Radio KISS Interface]]
Te6edf3type Tff7b72= Ta5d6ffKISSInterface
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# Serial port for the device
Te6edf3port Tff7b72= Ta5d6ff/dev/ttyUSB1
T8b949e# Set the serial baud-rate and other
T8b949e# configuration parameters.
Te6edf3speed Tff7b72= Ta5d6ff115200
Te6edf3databits Tff7b72= Ta5d6ff8
Te6edf3parity Tff7b72= Ta5d6ffnone
Te6edf3stopbits Tff7b72= Ta5d6ff1
T8b949e# Set the modem preamble.
Te6edf3preamble Tff7b72= Ta5d6ff150
T8b949e# Set the modem TX tail.
Te6edf3txtail Tff7b72= Ta5d6ff10
T8b949e# Configure CDMA parameters. These
T8b949e# settings are reasonable defaults.
Te6edf3persistence Tff7b72= Ta5d6ff200
Te6edf3slottime Tff7b72= Ta5d6ff20
T8b949e# You can configure the interface to send
T8b949e# out identification on the channel with
T8b949e# a set interval by configuring the
T8b949e# following two parameters. The KISS
T8b949e# interface will only ID if the set
T8b949e# interval has elapsed since it's last
T8b949e# actual transmission. The interval is
T8b949e# configured in seconds.
T8b949e# This option is commented out and not
T8b949e# used by default.
T8b949e# id_callsign = MYCALL-0
T8b949e# id_interval = 600
T8b949e# Whether to use KISS flow-control.
T8b949e# This is useful for modems that have
T8b949e# a small internal packet buffer, but
T8b949e# support packet flow control instead.
Te6edf3flow_control Tff7b72= Ta5d6fffalse
Tb4b4b4.. Tff7b72_interfaces-ax25:
Tc9d1d9AX.25 KISS Interface
Tc9d1d9====================
If you're using Reticulum on amateur radio spectrum, you might want to
use the AX.25 KISS interface. This way, Reticulum will automatically
encapsulate it's traffic in AX.25 and also identify your stations
transmissions with your callsign and SSID.
Only do this if you really need to! Reticulum doesn't need the AX.25
layer for anything, and it incurs extra overhead on every packet to
encapsulate in AX.25.
A more efficient way is to use the plain KISS interface with the
beaconing functionality described above.
Tb4b4b4.. Tff7b72warningTb4b4b4::
Radio frequency spectrum is a legally controlled resource, and legislation
varies widely around the world. It is your responsibility to be aware of any
relevant regulation for your location, and to make decisions accordingly.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[Packet Radio AX.25 KISS Interface]]
Te6edf3type Tff7b72= Ta5d6ffAX25KISSInterface
T8b949e# Set the station callsign and SSID
Te6edf3callsign Tff7b72= Ta5d6ffNO1CLL
Te6edf3ssid Tff7b72= Ta5d6ff0
T8b949e# Enable interface if you want use it!
Te6edf3enabled Tff7b72= Ta5d6ffyes
T8b949e# Serial port for the device
Te6edf3port Tff7b72= Ta5d6ff/dev/ttyUSB2
T8b949e# Set the serial baud-rate and other
T8b949e# configuration parameters.
Te6edf3speed Tff7b72= Ta5d6ff115200
Te6edf3databits Tff7b72= Ta5d6ff8
Te6edf3parity Tff7b72= Ta5d6ffnone
Te6edf3stopbits Tff7b72= Ta5d6ff1
T8b949e# Set the modem preamble. A 150ms
T8b949e# preamble should be a reasonable
T8b949e# default, but may need to be
T8b949e# increased for radios with slow-
T8b949e# opening squelch and long TX/RX
T8b949e# turnaround
Te6edf3preamble Tff7b72= Ta5d6ff150
T8b949e# Set the modem TX tail. In most
T8b949e# cases this should be kept as low
T8b949e# as possible to not waste airtime.
Te6edf3txtail Tff7b72= Ta5d6ff10
T8b949e# Configure CDMA parameters. These
T8b949e# settings are reasonable defaults.
Te6edf3persistence Tff7b72= Ta5d6ff200
Te6edf3slottime Tff7b72= Ta5d6ff20
T8b949e# Whether to use KISS flow-control.
T8b949e# This is useful for modems with a
T8b949e# small internal packet buffer.
Te6edf3flow_control Tff7b72= Ta5d6fffalse
Tb4b4b4.. Tff7b72_interfaces-discoverable:
Tc9d1d9Discoverable Interfaces
Tc9d1d9=======================
Reticulum includes a powerful system for publishing your local interfaces to the wider network, allowing other peers to Te6edf3:ref:Te6edf3`discover, validate, and automatically connect to them<using-interface_discovery>`. This feature is particularly useful for creating decentralized networks where peers can dynamically find entrypoints, such as public Internet gateways or local radio access points, without relying on static configuration files or centralized directories.
When an interface is made **discoverable**, your Reticulum instance will periodically broadcast an announce packet containing the connection details and parameters required for other peers to establish a connection. These announces are propagated over the network using the standard Reticulum announce mechanism using the Ta5d6ff``Ta5d6ffrnstransport.discovery.interfaceTa5d6ff`` destination type.
Tb4b4b4.. Tff7b72noteTb4b4b4::
To use the interface discovery functionality, the Ta5d6ff``Ta5d6ffLXMFTa5d6ff`` module must be installed in your Python environment. You can install it using pip:
Tb4b4b4 .. Tff7b72codeTb4b4b4:: Tff7b72sh
pip install lxmf
Tc9d1d9Enabling Discovery
Tc9d1d9------------------
Interface discovery is enabled on a per-interface basis. To make a specific interface discoverable, you must add the Ta5d6ff``Ta5d6ffdiscoverableTa5d6ff`` option to that interface's configuration block and set it to Ta5d6ff``Ta5d6ffyesTa5d6ff``.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[My Public Gateway]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3...
Te6edf3discoverable Tff7b72= Ta5d6ffyes
Once enabled, Reticulum will automatically handle the generation, signing, stamping, and broadcasting of the discovery announces. It is not *required* to enable Transport to publish interface discovery information, but for most use cases where you want others to connect to you, you will likely want Ta5d6ff``Ta5d6ffenable_transportTa5d6ff`` set to Ta5d6ff``Ta5d6ffyesTa5d6ff`` in the Ta5d6ff``Ta5d6ff[reticulum]Ta5d6ff`` section of your configuration.
Tc9d1d9Discovery Parameters
Tc9d1d9--------------------
When Ta5d6ff``Ta5d6ffdiscoverableTa5d6ff`` is enabled, a variety of additional options become available to control how the interface is presented to the network. These parameters allow you to fine-tune the metadata, security requirements, and visibility of your interface.
**Basic Metadata**
Ta5d6ff``Ta5d6ffdiscovery_nameTa5d6ff``
A human-readable name for the interface. This name will be displayed to users on remote systems when they list discovered interfaces. If not specified, the interface name (the section header) will be used.
Ta5d6ff``Ta5d6ffannounce_intervalTa5d6ff``
The interval in minutes between successive discovery announces for this interface. Default is 360 minutes (6 hours). For stable, long-running infrastructure, higher intervals (12 to 22 hours) are usually sufficient and reduce network load. Minimum allowed value is 5 minutes (but expect to have your announces throttled if using intervals below one hour).
**Connectivity Specification**
Ta5d6ff``Ta5d6ffreachable_onTa5d6ff``
Specifies the address that remote peers should use to connect to this interface.
T79c0ff* For TCP and Backbone interfaces, this is typically the public IP address or hostname. Do not include the port, this is fetched automatically from the interface.
T79c0ff* For I2P interfaces, this is usually the I2P Ta5d6ff``Ta5d6ffb32Ta5d6ff`` address. This value is fetched automatically from the Ta5d6ff``Ta5d6ffI2PInterfaceTa5d6ff`` once it is up and connected to the I2P network, so you should not set this manually, unless you absolutely know what you're doing.
**Dynamic Resolution:** This option also accepts a path to an external executable script or binary. If a path is provided, Reticulum will execute the script and use its Ta5d6ff``Ta5d6ffstdoutTa5d6ff`` as the reachability address. This is useful for devices behind dynamic DNS, NATs, or complex cloud environments where the external IP is not known locally. The script must simply print the address to stdout and exit.
Tb4b4b4.. Tff7b72noteTb4b4b4::
When using an executable script for Ta5d6ff``Ta5d6ffreachable_onTa5d6ff``, Reticulum expects the script to output only the IP address or hostname to Ta5d6ff``Ta5d6ffstdoutTa5d6ff``, followed by a newline character. Any additional output or errors may cause the resolution to fail. Ensure the script has executable permissions and is robust against temporary network failures.
A minimal example of a script that resolves the externally available, public IP of an internet-connected system could look like this:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72bash
T8b949e#!/bin/bash
curl -s ip.me
Tffa657exit Te6edf3$?
On a real system, you should make the script robust enough to deal with intermittent Internet or service failures, such that the script *always* returns a sensible value, or if not possible at least exits with a non-zero exit return code, so Reticulum knows the output is invalid.
**Security & Cost**
Ta5d6ff``Ta5d6ffdiscovery_stamp_valueTa5d6ff``
Defines the proof-of-work difficulty for the cryptographic stamp included in the announce. This value acts as a cost barrier to prevent network flooding. The default value is Ta5d6ff``Ta5d6ff14Ta5d6ff``. Increasing this value makes it computationally more expensive to generate an announce, which can be useful to prevent spam on very large networks, but it also increases CPU load on your system when generating announces. Stamps are cached, and only generated if interface information changes, or at instance restart. If you have the computational resources, it is generally advisable to use as high a stamp value as possible.
**Privacy & Encryption**
Ta5d6ff``Ta5d6ffdiscovery_encryptTa5d6ff``
If set to Ta5d6ff``Ta5d6ffyesTa5d6ff``, the discovery announce payload will be encrypted. To decrypt the announce, remote peers must possess the *network identity* configured for your instance (see Ta5d6ff``Ta5d6ffnetwork_identityTa5d6ff`` in the Ta5d6ff``Ta5d6ff[reticulum]Ta5d6ff`` section). This allows you to publish private interfaces that are only discoverable to specific trusted networks.
Tb4b4b4.. Tff7b72importantTb4b4b4::
If you enable Ta5d6ff``Ta5d6ffdiscovery_encryptTa5d6ff`` but do not configure a valid Ta5d6ff``Ta5d6ffnetwork_identityTa5d6ff`` in the Ta5d6ff``Ta5d6ff[reticulum]Ta5d6ff`` section of your configuration, Reticulum will abort the interface discovery announce. Encryption requires a valid network identity key to function.
Ta5d6ff``Ta5d6ffpublish_ifacTa5d6ff``
If set to Ta5d6ff``Ta5d6ffyesTa5d6ff``, the Interface Access Code (IFAC) name and passphrase for this interface will be included in the discovery announce. This allows peers to automatically configure the correct authentication parameters when connecting to the interface.
**Physical Location**
Ta5d6ff``Ta5d6fflatitudeTa5d6ff``, Ta5d6ff``Ta5d6fflongitudeTa5d6ff``, Ta5d6ff``Ta5d6ffheightTa5d6ff``
Optional physical coordinates for the interface. These are useful for mapping discovered interfaces geographically or for clients to automatically select the nearest access point. Coordinates should be in decimal degrees, height in meters.
**Radio Parameters**
For physical radio interfaces like Ta5d6ff``Ta5d6ffRNodeInterfaceTa5d6ff`` or Ta5d6ff``Ta5d6ffKISSInterfaceTa5d6ff``, the following optional parameters allow you to broadcast the operating frequency and characteristics, allowing clients to verify compatibility before connecting:
Ta5d6ff``Ta5d6ffdiscovery_frequencyTa5d6ff``
The operating frequency in Hz. Auto-configured on RNode interfaces. Necessary on KISS-based radio interfaces and Ta5d6ff``Ta5d6ffTCPClientInterfacesTa5d6ff`` connecting to radio modems.
Ta5d6ff``Ta5d6ffdiscovery_bandwidthTa5d6ff``
The signal bandwidth in Hz. Auto-configured on RNode interfaces. Useful on KISS-based radio interfaces and Ta5d6ff``Ta5d6ffTCPClientInterfacesTa5d6ff`` connecting to radio modems.
Ta5d6ff``Ta5d6ffdiscovery_modulationTa5d6ff``
The modulation type or scheme. Auto-configured on RNode interfaces, but highly advisable to include on other radio-based interfaces.
Tc9d1d9Interface Modes
Tc9d1d9---------------
When you enable discovery on an interface, Reticulum enforces certain interface modes to ensure the interface is actually useful for remote peers.
If an interface is configured as Ta5d6ff``Ta5d6ffdiscoverableTa5d6ff``, but its mode is not explicitly set to Ta5d6ff``Ta5d6ffgatewayTa5d6ff`` (for server-style interfaces like Ta5d6ff``Ta5d6ffBackboneInterfaceTa5d6ff`` or Ta5d6ff``Ta5d6ffTCPServerInterfaceTa5d6ff``) or Ta5d6ff``Ta5d6ffaccess_pointTa5d6ff`` (for radio interfaces like Ta5d6ff``Ta5d6ffRNodeInterfaceTa5d6ff``), Reticulum will automatically configure the appropriate mode and log a notice.
For example, if you enable discovery on a Ta5d6ff``Ta5d6ffRNodeInterfaceTa5d6ff`` without specifying the mode, Reticulum will automatically set it to Ta5d6ff``Ta5d6ffaccess_pointTa5d6ff`` mode.
Tc9d1d9Security Considerations
Tc9d1d9-----------------------
When making interfaces discoverable, you are effectively broadcasting an invitation to connect to your system. It is important to understand the security implications of the configuration options you choose.
**Publishing Credentials**
If you enable Ta5d6ff``Ta5d6ffpublish_ifac = yesTa5d6ff``, your interface's authentication passphrase will be included in the announce. If you are operating a public network and want anyone to connect, this is acceptable. However, if you wish to restrict access to a specific group of users, you **must** enable Ta5d6ff``Ta5d6ffdiscovery_encrypt = yesTa5d6ff``. This ensures that only peers possessing the correct Ta5d6ff``Ta5d6ffnetwork_identityTa5d6ff`` can decode the passphrase.
**Topology Exposure**
A discoverable interface announces its presence, location (if configured), and capabilities to the network. Even if the connection details are encrypted, the *fact* that a connectable node exists within a certain network becomes public information. In high-security or scenarios requiring operational secrecy, consider the implications of advertising your infrastructure's existence.
Tc9d1d9Example Configuration
Tc9d1d9---------------------
Below is an example configuration for a public backbone gateway. This configuration publishes a high-value, publicly discoverable interface, that anyone can connect to.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[My Public Gateway]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3mode Tff7b72= Ta5d6ffgateway
Te6edf3listen_on Tff7b72= Ta5d6ff0.0.0.0
Te6edf3port Tff7b72= Ta5d6ff4242
T8b949e# Enable Discovery
Te6edf3discoverable Tff7b72= Ta5d6ffyes
T8b949e# Interface Details
Te6edf3discovery_name Tff7b72= Ta5d6ffRegion A Public Entrypoint
Te6edf3announce_interval Tff7b72= Ta5d6ff720
T8b949e# Use external script to resolve dynamic IP
Te6edf3reachable_on Tff7b72= Ta5d6ff/usr/local/bin/get_external_ip.sh
T8b949e# Generate high stamp value
Te6edf3discovery_stamp_value Tff7b72= Ta5d6ff24
T8b949e# Optional location data
Te6edf3latitude Tff7b72= Ta5d6ff51.99714
Te6edf3longitude Tff7b72= Ta5d6ff-0.74195
Te6edf3height Tff7b72= Ta5d6ff15
The next example create an encrypted discovery-enabled interface, requiring a specific network identity to decode, and includes IFAC credentials for seamless authentication.
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[[My Private Gateway]]
Te6edf3type Tff7b72= Ta5d6ffBackboneInterface
Te6edf3mode Tff7b72= Ta5d6ffgateway
Te6edf3listen_on Tff7b72= Ta5d6ff0.0.0.0
Te6edf3port Tff7b72= Ta5d6ff5858
Te6edf3network_name Tff7b72= Ta5d6ffinternal_1
Te6edf3passphrase Tff7b72= Ta5d6ffMevpekyafshak5Wr
T8b949e# Enable Discovery
Te6edf3discoverable Tff7b72= Ta5d6ffyes
T8b949e# Interface Details
Te6edf3discovery_name Tff7b72= Ta5d6ffRegion A Private Backbone
Te6edf3announce_interval Tff7b72= Ta5d6ff720
T8b949e# Use external script to resolve dynamic IP
Te6edf3reachable_on Tff7b72= Ta5d6ff/usr/local/bin/get_external_ip.sh
T8b949e# Target stamp value
Te6edf3discovery_stamp_value Tff7b72= Ta5d6ff22
T8b949e# Encrypt announces for our network only
Te6edf3discovery_encrypt Tff7b72= Ta5d6ffyes
T8b949e# Include credentials so trusted
T8b949e# peers can connect automatically
Te6edf3publish_ifac Tff7b72= Ta5d6ffyes
T8b949e# Optional location data
Te6edf3latitude Tff7b72= Ta5d6ff34.06915
Te6edf3longitude Tff7b72= Ta5d6ff-118.44318
Te6edf3height Tff7b72= Ta5d6ff15
In the Ta5d6ff``Ta5d6ff[reticulum]Ta5d6ff`` section of your configuration, you would define the network identity used for encryption as follows:
Tb4b4b4.. Tff7b72codeTb4b4b4:: Tff7b72ini
Tff7b72[reticulum]
Te6edf3...
T8b949e# The identity used to sign/encrypt discovery announces
Te6edf3network_identity Tff7b72= Ta5d6ff~/.reticulum/storage/identities/my_network_identity
Te6edf3...
With these configuration options applied, your Reticulum instance will actively participate in the network's discovery ecosystem. Other peers running Reticulum with discovery enabled will be able to see your interface, validate its cryptographic stamp, and (depending on their configuration) automatically connect to it.
For information on how to use these discovered interfaces and configure your system to auto-connect to them, refer to the Te6edf3:ref:Te6edf3`Discovering Interfaces<using-interface_discovery>` chapter.
Tb4b4b4.. Tff7b72_interfaces-options:
Tc9d1d9Common Interface Options
Tc9d1d9========================
A number of general configuration options are available on most interfaces.
These can be used to control various aspects of interface behaviour.
T79c0ff* | The Ta5d6ff``Ta5d6ffenabledTa5d6ff`` option tells Reticulum whether or not
to bring up the interface. Defaults to Ta5d6ff``Ta5d6ffFalseTa5d6ff``. For any
interface to be brought up, the Ta5d6ff``Ta5d6ffenabledTa5d6ff`` option
must be set to Ta5d6ff``Ta5d6ffTrueTa5d6ff`` or Ta5d6ff``Ta5d6ffYesTa5d6ff``.
T79c0ff* | The Ta5d6ff``Ta5d6ffmodeTa5d6ff`` option allows selecting the high-level behaviour
of the interface from a number of options.
T79c0ff- The default value is Ta5d6ff``Ta5d6fffullTa5d6ff``. In this mode, all discovery,
meshing and transport functionality is available.
T79c0ff- In the Ta5d6ff``Ta5d6ffaccess_pointTa5d6ff`` (or shorthand Ta5d6ff``Ta5d6ffapTa5d6ff``) mode, the
interface will operate as a network access point. In this
mode, announces will not be automatically broadcasted on
the interface, and paths to destinations on the interface
will have a much shorter expiry time. This mode is useful
for creating interfaces that are mostly quiet, unless when
someone is actually using them. An example of this could
be a radio interface serving a wide area, where users are
expected to connect momentarily, use the network, and then
disappear again.
T79c0ff* | The Ta5d6ff``Ta5d6ffoutgoingTa5d6ff`` option sets whether an interface is allowed
to transmit. Defaults to Ta5d6ff``Ta5d6ffTrueTa5d6ff``. If set to Ta5d6ff``Ta5d6ffFalseTa5d6ff`` or Ta5d6ff``Ta5d6ffNoTa5d6ff``
the interface will only receive data, and never transmit.
T79c0ff* | The Ta5d6ff``Ta5d6ffnetwork_nameTa5d6ff`` option sets the virtual network name for
the interface. This allows multiple separate network segments
to exist on the same physical channel or medium.
T79c0ff* | The Ta5d6ff``Ta5d6ffpassphraseTa5d6ff`` option sets an authentication passphrase on
the interface. This option can be used in conjunction with the
Ta5d6ff``Ta5d6ffnetwork_nameTa5d6ff`` option, or be used alone.
T79c0ff* | The Ta5d6ff``Ta5d6ffifac_sizeTa5d6ff`` option allows customising the length of the
Interface Authentication Codes carried by each packet on named
and/or authenticated network segments. It is set by default to
a size suitable for the interface in question, but can be set
to a custom size between 8 and 512 bits by using this option.
In normal usage, this option should not be changed from the
default.
T79c0ff* | The Ta5d6ff``Ta5d6ffannounce_capTa5d6ff`` option lets you configure the maximum
bandwidth to allocate, at any given time, to propagating
announces and other network upkeep traffic. It is configured at
2% by default, and should normally not need to be changed. Can
be set to any value between Ta5d6ff``Ta5d6ff1Ta5d6ff`` and Ta5d6ff``Ta5d6ff100Ta5d6ff``.
*If an interface exceeds its announce cap, it will queue announces
for later transmission. Reticulum will always prioritise propagating
announces from nearby nodes first. This ensures that the local
topology is prioritised, and that slow networks are not overwhelmed
by interconnected fast networks.*
*Destinations that are rapidly re-announcing will be down-prioritised
further. Trying to get "first-in-line" by announce spamming will have
the exact opposite effect: Getting moved to the back of the queue every
time a new announce from the excessively announcing destination is received.*
*This means that it is always beneficial to select a balanced
announce rate, and not announce more often than is actually necesarry
for your application to function.*
T79c0ff* | The Ta5d6ff``Ta5d6ffbitrateTa5d6ff`` option configures the interface bitrate.
Reticulum will use interface speeds reported by hardware, or
try to guess a suitable rate when the hardware doesn't report
any. In most cases, the automatically found rate should be
sufficient, but it can be configured by using the Ta5d6ff``Ta5d6ffbitrateTa5d6ff``
option, to set the interface speed in *bits per second*.
T79c0ff* | The Ta5d6ff``Ta5d6ffbootstrap_onlyTa5d6ff`` option designates an interface as a temporary
bridge for initial connectivity. If this option is enabled, the
interface will be monitored and automatically detached once the
number of auto-connected interfaces reaches the limit configured by
Ta5d6ff``Ta5d6ffautoconnect_discovered_interfacesTa5d6ff``. This is particularly useful
for using a slow or expensive connection (such as a single LoRa
link or a remote TCP tunnel) solely to discover better local
infrastructure, which then supersedes the bootstrap interface.
Tb4b4b4.. Tff7b72_interfaces-modes:
Tc9d1d9Interface Modes
Tc9d1d9===============
The optional Ta5d6ff``Ta5d6ffmodeTa5d6ff`` setting is available on all interfaces, and allows
selecting the high-level behaviour of the interface from a number of modes.
These modes affect how Reticulum selects paths in the network, how announces
are propagated, how long paths are valid and how paths are discovered.
Configuring modes on interfaces is **not** strictly necessary, but can be useful
when building or connecting to more complex networks. If your Reticulum
instance is not running a Transport Node, it is rarely useful to configure
interface modes, and in such cases interfaces should generally be left in
the default mode.
T79c0ff* | The default mode is Ta5d6ff``Ta5d6fffullTa5d6ff``. In this mode, all discovery,
meshing and transport functionality is activated.
T79c0ff* | The Ta5d6ff``Ta5d6ffgatewayTa5d6ff`` mode (or shorthand Ta5d6ff``Ta5d6ffgwTa5d6ff``) also has all
discovery, meshing and transport functionality available,
but will additionally try to discover unknown paths on
behalf of other nodes residing on the Ta5d6ff``Ta5d6ffgatewayTa5d6ff`` interface.
If Reticulum receives a path request for an unknown
destination, from a node on a Ta5d6ff``Ta5d6ffgatewayTa5d6ff`` interface, it
will try to discover this path via all other active interfaces,
and forward the discovered path to the requestor if one is
found.
Tff7b72| If you want to allow other nodes to widely resolve paths or connect
to a network via an interface, it might be useful to put it in this
mode. By creating a chain of Ta5d6ff``Ta5d6ffgatewayTa5d6ff`` interfaces, other
nodes will be able to immediately discover paths to any
destination along the chain.
Tff7b72| *Please note!* It is the interface *facing the clients* that
must be put into Ta5d6ff``Ta5d6ffgatewayTa5d6ff`` mode for this to work, not
the interface facing the wider network (for this, the Ta5d6ff``Ta5d6ffboundaryTa5d6ff``
mode can be useful, though).
T79c0ff* | In the Ta5d6ff``Ta5d6ffaccess_pointTa5d6ff`` (or shorthand Ta5d6ff``Ta5d6ffapTa5d6ff``) mode, the
interface will operate as a network access point. In this
mode, announces will not be automatically broadcasted on
the interface, and paths to destinations on the interface
will have a much shorter expiry time. In addition, path
requests from clients on the access point interface will
be handled in the same way as the Ta5d6ff``Ta5d6ffgatewayTa5d6ff`` interface.
Tff7b72| This mode is useful for creating interfaces that remain
quiet, until someone actually starts using them. An example
of this could be a radio interface serving a wide area,
where users are expected to connect momentarily, use the
network, and then disappear again.
T79c0ff* | The Ta5d6ff``Ta5d6ffroamingTa5d6ff`` mode should be used on interfaces that are
roaming (physically mobile), seen from the perspective of
other nodes in the network. As an example, if a vehicle is
equipped with an external LoRa interface, and an internal,
WiFi-based interface, that serves devices that are moving
*with* the vehicle, the external LoRa interface should be
configured as Ta5d6ff``Ta5d6ffroamingTa5d6ff``, and the internal interface can
be left in the default mode. With transport enabled, such
a setup will allow all internal devices to reach each other,
and all other devices that are available on the LoRa side
of the network, when they are in range. Devices on the LoRa
side of the network will also be able to reach devices
internal to the vehicle, when it is in range. Paths via
Ta5d6ff``Ta5d6ffroamingTa5d6ff`` interfaces also expire faster.
T79c0ff* | The purpose of the Ta5d6ff``Ta5d6ffboundaryTa5d6ff`` mode is to specify interfaces
that establish connectivity with network segments that are
significantly different than the one this node exists on.
As an example, if a Reticulum instance is part of a LoRa-based
network, but also has a high-speed connection to a
public Transport Node available on the Internet, the interface
connecting over the Internet should be set to Ta5d6ff``Ta5d6ffboundaryTa5d6ff`` mode.
For a table describing the impact of all modes on announce propagation,
please see the Te6edf3:ref:Te6edf3`Announce Propagation Rules<understanding-announcepropagation>` section.
Tb4b4b4.. Tff7b72_interfaces-announcerates:
Tc9d1d9Announce Rate Control
Tc9d1d9=====================
The built-in announce control mechanisms and the default Ta5d6ff``Ta5d6ffannounce_capTa5d6ff``
option described above are sufficient most of the time, but in some cases, especially on fast
interfaces, it may be useful to control the target announce rate. Using the
Ta5d6ff``Ta5d6ffannounce_rate_targetTa5d6ff``, Ta5d6ff``Ta5d6ffannounce_rate_graceTa5d6ff`` and Ta5d6ff``Ta5d6ffannounce_rate_penaltyTa5d6ff``
options, this can be done on a per-interface basis, and moderates the *rate at
which received announces are re-broadcasted to other interfaces*.
T79c0ff* | The Ta5d6ff``Ta5d6ffannounce_rate_targetTa5d6ff`` option sets the minimum amount of time,
in seconds, that should pass between received announces, for any one
destination. As an example, setting this value to Ta5d6ff``Ta5d6ff3600Ta5d6ff`` means that
announces *received* on this interface will only be re-transmitted and
propagated to other interfaces once every hour, no matter how often they
are received.
T79c0ff* | The optional Ta5d6ff``Ta5d6ffannounce_rate_graceTa5d6ff`` defines the number of times a destination
can violate the announce rate before the target rate is enforced.
T79c0ff* | The optional Ta5d6ff``Ta5d6ffannounce_rate_penaltyTa5d6ff`` configures an extra amount of
time that is added to the normal rate target. As an example, if a penalty
of Ta5d6ff``Ta5d6ff7200Ta5d6ff`` seconds is defined, once the rate target is enforced, the
destination in question will only have its announces propagated every
3 hours, until it lowers its actual announce rate to within the target.
These mechanisms, in conjunction with the Ta5d6ff``Ta5d6ffannouce_capTa5d6ff`` mechanisms mentioned
above means that it is essential to select a balanced announce strategy for
your destinations. The more balanced you can make this decision, the easier
it will be for your destinations to make it into slower networks that many hops
away. Or you can prioritise only reaching high-capacity networks with more frequent
announces.
Current statistics and information about announce rates can be viewed using the
Ta5d6ff``Ta5d6ffrnpath -rTa5d6ff`` command.
It is important to note that there is no one right or wrong way to set up announce
rates. Slower networks will naturally tend towards using less frequent announces to
conserve bandwidth, while very fast networks can support applications that
need very frequent announces. Reticulum implements these mechanisms to ensure
that a large span of network types can seamlessly *co-exist* and interconnect.
Tb4b4b4.. Tff7b72_interfaces-ingress-control:
Tc9d1d9New Destination Rate Limiting
Tc9d1d9=============================
On public interfaces, where anyone may connect and announce new destinations,
it can be useful to control the rate at which announces for *new* destinations are
processed.
If a large influx of announces for newly created or previously unknown destinations
occur within a short amount of time, Reticulum will place these announces on hold,
so that announce traffic for known and previously established destinations can
continue to be processed without interruptions.
After the burst subsides, and an additional waiting period has passed, the held
announces will be released at a slow rate, until the hold queue is cleared. This
also means, that should a node decide to connect to a public interface, announce
a large amount of bogus destinations, and then disconnect, these destination will
never make it into path tables and waste network bandwidth on retransmitted
announces.
**It's important to note** that the ingress control works at the level of *individual
sub-interfaces*. As an example, this means that one client on a Te6edf3:ref:Te6edf3`TCP Server Interface<interfaces-tcps>`
cannot disrupt processing of incoming announces for other connected clients on the same
Te6edf3:ref:Te6edf3`TCP Server Interface<interfaces-tcps>`. All other clients on the same interface will still have new announces
processed without interruption.
By default, Reticulum will handle this automatically, and ingress announce
control will be enabled on interface where it is sensible to do so. It should
generally not be neccessary to modify the ingress control configuration,
but all the parameters are exposed for configuration if needed.
T79c0ff* | The Ta5d6ff``Ta5d6ffingress_controlTa5d6ff`` option tells Reticulum whether or not
to enable announce ingress control on the interface. Defaults to
Ta5d6ff``Ta5d6ffTrueTa5d6ff``.
T79c0ff* | The Ta5d6ff``Ta5d6ffic_new_timeTa5d6ff`` option configures how long (in seconds) an
interface is considered newly spawned. Defaults to Ta5d6ff``Ta5d6ff2*60*60Ta5d6ff`` seconds. This
option is useful on publicly accessible interfaces that spawn new
sub-interfaces when a new client connects.
T79c0ff* | The Ta5d6ff``Ta5d6ffic_burst_freq_newTa5d6ff`` option sets the maximum announce ingress
frequency for newly spawned interfaces. Defaults to Ta5d6ff``Ta5d6ff3.5Ta5d6ff``
announces per second.
T79c0ff* | The Ta5d6ff``Ta5d6ffic_burst_freqTa5d6ff`` option sets the maximum announce ingress
frequency for other interfaces. Defaults to Ta5d6ff``Ta5d6ff12Ta5d6ff`` announces
per second.
*If an interface exceeds its burst frequency, incoming announces
for unknown destinations will be temporarily held in a queue, and
not processed until later.*
T79c0ff* | The Ta5d6ff``Ta5d6ffic_max_held_announcesTa5d6ff`` option sets the maximum amount of
unique announces that will be held in the queue. Any additional
unique announces will be dropped. Defaults to Ta5d6ff``Ta5d6ff256Ta5d6ff`` announces.
T79c0ff* | The Ta5d6ff``Ta5d6ffic_burst_holdTa5d6ff`` option sets how much time (in seconds) must
pass after the burst frequency drops below its threshold, for the
announce burst to be considered cleared. Defaults to Ta5d6ff``Ta5d6ff60Ta5d6ff``
seconds.
T79c0ff* | The Ta5d6ff``Ta5d6ffic_burst_penaltyTa5d6ff`` option sets how much time (in seconds) must
pass after the burst is considered cleared, before held announces can
start being released from the queue. Defaults to Ta5d6ff``Ta5d6ff5*60Ta5d6ff``
seconds.
T79c0ff* | The Ta5d6ff``Ta5d6ffic_held_release_intervalTa5d6ff`` option sets how much time (in seconds)
must pass between releasing each held announce from the queue. Defaults
to Ta5d6ff``Ta5d6ff30Ta5d6ff`` seconds.
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────